<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"  xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-type" content="text/html+xhtml; charset=UTF-8" />
  <meta name="description" content="Patch-Manager - Client/Server Protocol" />

  <title>Patch-Manager - Client/Server Protocol</title>
  <link rel="stylesheet" href="style/style.css" type="text/css" />
</head>
<body>
<h1>Patch-Manager - Client/Server Protocol</h1>
<p><a href="http://www.ruinwesen.com/">http://www.ruinwesen.com/</a></p>

<table class="table_fields">
<thead><tr><th colspan="2">Changes</th></tr></thead>
<tbody>
<tr><td>2009-07-28</td><td>Added message overview table</td></tr>
<tr><td>2009-07-28</td><td>Draft: Modified some JSON objects and field names</td></tr>
<tr><td>2009-07-24</td><td>Draft: Modified some JSON objects and field names</td></tr>
</tbody>
</table>

<h1 id="message">1. Messages</h1>
<p>
	The protocol uses <a href="http://www.json.org">JSON</a> (JavaScript Object Notation)
	to encode messages send by the client or server.
	A message send by the client is a <a href="#request">request</a>. For each request the server answers
	with an appropriate <a href="#response">response</a>.
</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
	"protocol-id":PROTOCOL_ID,
	"action":"response"
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>PROTOCOL_ID</td><td>a string containing the protocol id. The id of the protocol as described in this document is "1.0" (without quotes).</td></tr>
</tbody>
</table>


<h1 id="message">2. Message Overview</h1>

<h2>Request / Response</h2>
<table class="table_fields">
<thead>
	<tr><th>Request</th> <th>Authenticated</th> <th>Response</th></tr>
</thead>
<tbody>
	<tr><td>Store New Patch</td><td>yes</td><td>Store New Patch Response</td></tr>
	<tr><td>Delete Patch</td><td>yes</td><td>Default Response</td></tr>
	<tr><td>Register New User</td><td>yes</td><td>Default Response</td></tr>
	<tr><td>Get Patch List</td><td>no</td><td>Get Patch List Response</td></tr>
</tbody>
</table>

<h2>Hierarchy</h2>
<table class="table_fields">
<thead>
	<tr><th>Base Class</th> <th>Class</th> <th>Abstract</th></tr>
</thead>
<tbody>
	<tr><td>-</td><td>Message</td><td>yes</td></tr>
	<tr><td>Message</td><td>Request</td><td>yes</td></tr>
	<tr><td>Request</td><td>Authenticated Request</td><td>yes</td></tr>
	<tr><td>Message</td><td>Response</td><td>yes</td></tr>	
	
	<tr><td>Authenticated Request</td><td>Store New Patch</td><td>no</td></tr>
	<tr><td>Authenticated Request</td><td>Delete Patch</td><td>no</td></tr>
	<tr><td>Authenticated Request</td><td>Register New User</td><td>no</td></tr>
	<tr><td>Request</td><td>Get Patch List</td><td>no</td></tr>
	
	<tr><td>Response</td><td>Default Response</td><td>no</td></tr>
	<tr><td>Default Response</td><td>Get Patch List Response</td><td>no</td></tr>
	<tr><td>Default Response</td><td>Store New Patch Response</td><td>no</td></tr>
</tbody>
</table>


<h1 id="request">3. Requests</h1>
<p>Each request-object is based on the <a href="#message">message</a>-object.
If not stated otherwise for each request the server sends the
<a href="#default_response">Default Response</a> object.
</p>

<h2>3.1 Register New User</h2>
<p>The request registers a new user.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "protocol-id":PROTOCOL_ID
  "auth":AUTH,
  "action":"register-new-user"
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>AUTH</td><td><a href="#objects_auth">Auth</a> object specifying the username/password pair of the new user</td></tr>
</tbody>
</table>

<h2>3.2 Store New Patch</h2>
<p>Upload / publish a patch.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "protocol-id":PROTOCOL_ID
  "auth":AUTH, 
  "action":"store-new-patch",
  "data":DATA,
  "data-md5":DATA_MD5,
  "patch-metadata":META
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>AUTH</td><td><a href="#objects_auth">Auth</a> object specifying the username/password pair of the new user</td></tr>
<tr><td>DATA</td><td>base64 encoded string of the the patch file (binary file)</td></tr>
<tr><td>DATA_MD5</td><td>base64 encoded string of the 32-byte MD5 checksum of the patch file</td></tr>
<tr><td>META</td><td><a href="#objects_meta">Meta</a> object specifying metadata of the patch file</td></tr>
</tbody>
</table>

<p><strong>Response:</strong> <a href="#store_new_patch_response">Store New Patch Response</a></p>

<h2>3.3 Delete Patch</h2>

<p>Delete a patch.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "protocol-id": PROTOCOL_ID
  "auth": AUTH, 
  "action": "delete-patch",
  "patch-id": PATCH_ID
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>AUTH</td><td><a href="#objects_auth">Auth</a> object specifying the username/password pair of the new user</td></tr>
<tr><td>PATCH_ID</td><td>string containing the patch-id</td></tr>
</tbody>
</table>

<h2>3.4 Get Patch List Request</h2>
<p>Get the list of patches stored by the server.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "protocol-id":PROTOCOL_ID,
  "action":"get-patch-source-list",
  "date-since":DATE_SINCE
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>DATE_SINCE</td><td>Requests a list of patches published since the specified date.
If a <code>null</code>-Value is specified then a list containing every patch is requested.
Otherwise the value must be a string containing a date encoded using the format <code>YYYY-MM-DD</code> (YYYY:year, MM:month [1-12], DD:day [1-31]).</td></tr>
</tbody>
</table>

<p><strong>Response:</strong> <a href="#patchlist_response">Get Patch List Response</a></p>

<h2>3.4 Get Server Info Request</h2>
<p>Get information about the server. The server replies with the default response. 
This message is a </p>
<h3>JSON Object:</h3>
<pre class="code"><code>{
  "protocol-id":PROTOCOL_ID,
  "action":"get-server-info"
}</code></pre>

<p><strong>Response:</strong> <a href="#getserverinfo_response">Get Server Info Response</a></p>



<h1 id="response">4. Response</h1>
<p>For each request the server sends a response indicating either success or failure 
of the operation. Each response-object is based on the <a href="#message">message</a>-object.</p>

<h2 id="default_response">4.1 Default Response object</h2>

<h3>JSON Object:</h3>
<pre class="code"><code>{
	"protocol-id":PROTOCOL_ID,
	"action":"response",
	"requested-action":REQUESTED_ACTION,
	"status":STATUS,
	"message":MESSAGE
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>REQUESTED_ACTION</td><td>name of the action this response originated from</td></tr>
<tr><td>STATUS</td><td>"ok" or "failed" indicating success or failure of performing the request/operation</td></tr>
<tr><td>MESSAGE</td><td>optional string containing a message, for instance the reason why the 
         operation failed</td></tr>
</tbody>
</table>

<h2 id="patchlist_response">4.2 Get Patch List Response</h2>
<p>The default response object having following additional fields:</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  ...
  "patch-source-list":PATCH_SOURCE_ARRAY
  "date-since":DATE_SINCE
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>PATCH_SOURCE_ARRAY</td><td>array of <a href="#objects_patchsource">PatchSource</a> objects</td></tr>
<tr><td>DATE_SINCE</td><td>The same value as specified in the <code>"date-since"</code> field of the request.</td></tr>
</tbody>
</table>

<h2 id="store_new_patch_response">4.3 Store New Patch Response</h2>
<p>The default response object having following additional fields:</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  ...
  "patch-source": PATCH_SOURCE
}</code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>PATCH_SOURCE</td><td><a href="#default_response">PatchSource</a> object containing id+url of the
stored patch</td></tr>
</tbody>
</table>







<h1>5. JSON Objects</h1>
<h2 id="objects_auth">5.1 Auth object</h2>
<p>The Auth object specifies the username/password pair which is required for certain operations.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "username": USERNAME,
  "password": PASSWORD
} </code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><a id="Auth_USERNAME">USERNAME</a></td><td>a string containing the username</td></tr>
<tr><td><a id="Auth_PASSWORD">PASSWORD</a></td><td>a string containing the password</td></tr>
</tbody>
</table>


<h2 id="objects_patchsource">5.2 PatchSource object</h2>
<p>The PatchSource object specifies patch-id and source.</p>

<h3>JSON Object:</h3>
<pre class="code"><code>{
  "patch-id": PATCH_ID,
  "patch-url": PATCH_URL
} </code></pre>

<h3>Fields</h3>
<table class="table_fields">
<thead>
<tr><th>Field</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><a id="Auth_USERNAME">PATCH_ID</a></td><td>a string containing the unique patch-id</td></tr>
<tr><td><a id="Auth_PASSWORD">PATCH_URL</a></td><td>a string containing the URL from which the patch can be downloaded</td></tr>
</tbody>
</table>


</body>
</html>